home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / DoOneEvent.3 < prev    next >
Text File  |  1995-07-21  |  10KB  |  325 lines
  1. '\"
  2. '\" Copyright (c) 1990-1992 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/DoOneEvent.3,v 1.8 93/04/01 09:41:17 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tk_DoOneEvent tkc
  206. .BS
  207. .SH NAME
  208. Tk_DoOneEvent, Tk_MainLoop, Tk_HandleEvent \- wait for events and
  209. invoke event handlers
  210. .SH SYNOPSIS
  211. .nf
  212. \fB#include <tk.h>\fR
  213. .sp
  214. int
  215. .VS
  216. \fBTk_DoOneEvent\fR(\fIflags\fR)
  217. .VE
  218. .sp
  219. \fBTk_MainLoop\fR()
  220. .sp
  221. \fBTk_HandleEvent\fR(\fIeventPtr\fR)
  222. .SH ARGUMENTS
  223. .AS XEvent *eventPtr
  224. .AP int flags in
  225. .VS
  226. This parameter is normally zero.  It may be an OR-ed combination
  227. of any of the following flag bits:  TK_X_EVENTS, TK_FILE_EVENTS,
  228. TK_TIMER_EVENTS, TK_IDLE_EVENTS, TK_ALL_EVENTS, or TK_DONT_WAIT.
  229. .VE
  230. .AP XEvent *eventPtr in
  231. Pointer to X event to dispatch to relevant handler(s).
  232. .BE
  233.  
  234. .SH DESCRIPTION
  235. .PP
  236. These three procedures are responsible for waiting for events
  237. and dispatching to event handlers created with the procedures
  238. \fBTk_CreateEventHandler\fR, \fBTk_CreateFileHandler\fR,
  239. \fBTk_CreateTimerHandler\fR, and \fBTk_DoWhenIdle\fR.
  240. \fBTk_DoOneEvent\fR is the key procedure.  It waits for a single
  241. event of any sort to occur, invokes the handler(s) for that
  242. event, and then returns.  \fBTk_DoOneEvent\fR first checks
  243. for X events and file-related events;  if one is found then
  244. it calls the handler(s) for the event and returns.  If there
  245. are no X or file events pending, then \fBTk_DoOneEvent\fR
  246. checks to see if timer callbacks are ready;  if so, it
  247. makes a single callback and returns.  If no timer callbacks
  248. are ready, \fBTk_DoOneEvent\fR checks for \fBTk_DoWhenIdle\fR
  249. callbacks;  if any are found, it invokes all of them and returns.
  250. Finally, if events or work have been found found, \fBTk_DoOneEvent\fR
  251. sleeps until a timer, file, or X event occurs;  then it processes
  252. the first event found (in the order given above) and returns.
  253. The normal return value is 1 to signify that some event or callback
  254. was processed.
  255. .PP
  256. If the \fIflags\fR argument to \fBTk_DoOneEvent\fR is non-zero then
  257. .VS
  258. it restricts the kinds of events that will be processed by
  259. \fBTk_DoOneEvent\fR.
  260. \fIFlags\fR may be an OR-ed combination of any of the following bits:
  261. .TP 24
  262. \fBTK_X_EVENTS\fR \-
  263. Process X events.
  264. .TP 24
  265. \fBTK_FILE_EVENTS\fR \-
  266. Process file events.
  267. .TP 24
  268. \fBTK_TIMER_EVENTS\fR \-
  269. Process timer events.
  270. .TP 24
  271. \fBTK_IDLE_EVENTS\fR \-
  272. Process \fBTk_DoWhenIdle\fR callbacks.
  273. .TP 24
  274. \fBTK_ALL_EVENTS\fR \-
  275. Process all kinds of events:  equivalent to OR-ing together all of the
  276. above flags or specifying none of them.
  277. .TP 24
  278. \fBTK_DONT_WAIT\fR \-
  279. Don't sleep:  process only events that are ready at the time of the
  280. call.
  281. .LP
  282. If any of the flags \fBTK_X_EVENTS\fR, \fBTK_FILE_EVENTS\fR,
  283. \fBTK_TIMER_EVENTS\fR, or \fBTK_IDLE_EVENTS\fR is set, then the only
  284. events that will be considered are those for which flags are set.
  285. Setting none of these flags is equivalent to the value
  286. \fBTK_ALL_EVENTS\fR, which causes all event types to be processed.
  287. .PP
  288. The \fBTK_DONT_WAIT\fR flag causes \fBTk_DoWhenIdle\fR not to put
  289. the process to sleep:  it will check for events but if none are found
  290. then it returns immediately with a return value of 0 to indicate
  291. that no work was done.
  292. \fBTk_DoOneEvent\fR will also return 0 without doing anything if
  293. \fIflags\fR is \fBTK_IDLE_EVENTS\fR and there are no
  294. \fBTk_DoWhenIdle\fR callbacks pending.
  295. .VE
  296. .PP
  297. \fBTk_MainLoop\fR is a procedure that loops repeatedly
  298. calling \fBTk_DoOneEvent\fR.  It returns only when there
  299. are no applications left in this process (i.e. no main windows
  300. exist anymore).  Most X applications will
  301. call \fBTk_MainLoop\fR after initialization;  the main
  302. execution of the application will consist entirely of
  303. callbacks invoked by \fBTk_DoOneEvent\fR.
  304. .PP
  305. \fBTk_HandleEvent\fR is a lower-level procedure invoked
  306. by \fBTk_DoOneEvent\fR.  It makes callbacks to any event
  307. handlers (created by calls to \fBTk_CreateEventHandler\fR)
  308. that match \fIeventPtr\fR and then returns.  In some cases
  309. it may be useful for an application to read events directly
  310. from X and dispatch them by calling \fBTk_HandleEvent\fR,
  311. without going through the additional mechanism provided
  312. by \fBTk_DoOneEvent\fR.
  313. .PP
  314. These procedures may be invoked recursively.  For example,
  315. it is possible to invoke \fBTk_DoOneEvent\fR recursively
  316. from a handler called by \fBTk_DoOneEvent\fR.  This sort
  317. of operation is useful in some modal situations, such
  318. as when a
  319. notifier has been popped up and an application wishes to
  320. wait for the user to click a button in the notifier before
  321. doing anything else.
  322.  
  323. .SH KEYWORDS
  324. callback, event, handler, idle, timer
  325.